Developer CD Series 1996 September: Technology Seed

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1996…eptember: Technology Seed / Mac Tech Seed Sep '96 / Mac Tech Seed Sep '96.toast / mac / QuickDraw 3D 1.5d7 / Interfaces / QD3DRenderer.h < prev next >

Wrap

C/C++ Source or Header | 1996-08-23 | 45.8 KB | 1,433 lines | [TEXT/R*ch]

/****************************************************************************** ** ** ** Module: QD3DRenderer.h ** ** ** ** ** ** Purpose: Renderer types and routines ** ** ** ** ** ** ** ** Copyright (C) 1992-1996 Apple Computer, Inc. All rights reserved. ** ** ** ** ** *****************************************************************************/ #ifndef QD3DRenderer_h #define QD3DRenderer_h #if defined(PRAGMA_ONCE) && PRAGMA_ONCE #pragma once #endif /* PRAGMA_ONCE */ #include "QD3DView.h" #include "QD3DSet.h" #if defined(WINDOW_SYSTEM_MACINTOSH) && WINDOW_SYSTEM_MACINTOSH #include "Events.h" #endif /* WINDOW_SYSTEM_MACINTOSH */ #if defined(WINDOW_SYSTEM_WIN32) && WINDOW_SYSTEM_WIN32 #include "windows.h" #endif /* WINDOW_SYSTEM_WIN32 */ #if defined(THINK_C) || defined(__SC__) #pragma options(!pack_enums, !align_arrays) #pragma SC options align=power #elif defined(__MWERKS__) #pragma enumsalwaysint on #pragma align_array_members off #pragma options align=native #elif defined(__PPCC__) #pragma options align=power #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__) #pragma options enum=int #endif #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /****************************************************************************** ** ** ** User Interface Things ** ** ** *****************************************************************************/ #if defined(WINDOW_SYSTEM_MACINTOSH) && WINDOW_SYSTEM_MACINTOSH /* * A callback to an application's event handling code. This is needed to * support movable modal dialogs. The dialog's event filter calls this * callback with events it does not handle. * If an application handles the event it should return kQ3True. * If the application does not handle the event it must return kQ3False and * the dialog's event filter will pass the event to the system unhandled. */ typedef TQ3Boolean (*TQ3MacOSDialogEventHandler)( EventRecord event); typedef struct TQ3DialogAnchor { TQ3MacOSDialogEventHandler clientEventHandler; } TQ3DialogAnchor; #elif defined(WINDOW_SYSTEM_WIN32) && WINDOW_SYSTEM_WIN32 typedef struct TQ3DialogAnchor { HWND ownerWindow; } TQ3DialogAnchor; #else /* ! WINDOW_SYSTEM_MACINTOSH && ! WINDOW_SYSTEM_WIN32 */ typedef struct TQ3DialogAnchor { char notUsed; /* place holder */ } TQ3DialogAnchor; #endif /* ! WINDOW_SYSTEM_MACINTOSH && ! WINDOW_SYSTEM_WIN32 */ /****************************************************************************** ** ** ** Renderer Functions ** ** ** *****************************************************************************/ QD3D_EXPORT TQ3RendererObject Q3Renderer_NewFromType( TQ3ObjectType rendererObjectType); QD3D_EXPORT TQ3ObjectType Q3Renderer_GetType( TQ3RendererObject renderer); /* * A bit set in this flag to indicates supported features */ #define kQ3RendererFeatureNone (0) /* Implements nothing */ #define kQ3RendererFeatureFlagHiddenSurfaceRemoval (1U << 0) /* Supports hidden surface removal */ #define kQ3RendererFeatureFlagHiddenSurfaceRemovalDeep (1U << 1) /* >= 24 bit hidden surface removal precision */ #define kQ3RendererFeatureFlagTexture (1U << 2) /* Textures */ #define kQ3RendererFeatureFlagTextureHighQuality (1U << 3) /* High-quality Textures (tri-linear or better) */ #define kQ3RendererFeatureFlagTextureColor (1U << 4) /* Full color modulation and highlight of textures */ #define kQ3RendererFeatureFlagTransparency (1U << 5) /* Transparency with RGB blending */ #define kQ3RendererFeatureFlagTransparencyAlpha (1U << 6) /* Transparency with alpha blending */ #define kQ3RendererFeatureFlagAntialiasing (1U << 7) /* AntiAliasing */ #define kQ3RendererFeatureFlagShadows (1U << 8) /* Shadows */ typedef unsigned long TQ3RendererFeatureFlags; /* * Q3Renderer_GetEditFeatures * Returns a mask of variable features in the renderer. A 1 bit does not * indicate that this feature is currently "on", only that it is editable. * * You may "set" or "unset" these features using Q3Renderer_SetFeatures. */ QD3D_EXPORT TQ3Status Q3Renderer_GetEditFeatures( TQ3RendererObject renderer, TQ3RendererFeatureFlags *editableFlags); /* * Q3Renderer_GetFeatures * Returns a mask of currently set features in the renderer. A 1 bit * indicates that this feature is currently "on". Some features may be * available but not turned on. Some features may be on (always), but * not editable. * * To get a complete mask of all available features, do: * * Q3Renderer_GetEditFeatures(renderer, &editable); * Q3Renderer_GetFeatures(renderer, &features); * totalFeatures = editable | features; */ QD3D_EXPORT TQ3Status Q3Renderer_GetFeatures( TQ3RendererObject renderer, TQ3RendererFeatureFlags *flags); /* * Q3Renderer_SetFeatures * Turn on or off editable features in a renderer. * Operation is: * newRendererFlags = * (oldRendererFlags & ~editableFlags) | * (flags & editableFlags); */ QD3D_EXPORT TQ3Status Q3Renderer_SetFeatures( TQ3RendererObject renderer, TQ3RendererFeatureFlags flags); #if defined(QD3D_OBSOLETE) && QD3D_OBSOLETE /* * Non-blocking, flush all buffered graphics to rasterizer. May or * may not update the draw context. * * This function has been replaced by Q3View_Flush */ QD3D_EXPORT TQ3Status Q3Renderer_Flush( TQ3RendererObject renderer, TQ3ViewObject view); /* * Blocking, flush all buffered graphics to rasterizer and update * draw context. * * This function has been replaced by Q3View_Sync */ QD3D_EXPORT TQ3Status Q3Renderer_Sync( TQ3RendererObject renderer, TQ3ViewObject view); #endif /* QD3D_OBSOLETE */ /* * Q3Renderer_HasModalConfigure * Determine if this renderer has a modal settings dialog. * * Q3Renderer_ModalConfigure * Have the renderer pop up a modal dialog box to configure its settings. * dialogAnchor - is platform specific data passed by the client to support * movable modal dialogs. * MacOS: this is a callback to the calling application's event handler. * The renderer calls this function with events not handled by the * settings dialog. This is necessary in order to support movable modal * dialogs. An application's event handler must return kQ3True if it * handles the event passed to the callback or kQ3False if not. * An application which doesn't want to support a movable modal configure * dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor. * Win32: this is the HWND of the owning window (typically an application's * main window). * canceled - returns a boolean inditacating that the user canceled the * dialog. * */ QD3D_EXPORT TQ3Boolean Q3Renderer_HasModalConfigure( TQ3RendererObject renderer); QD3D_EXPORT TQ3Status Q3Renderer_ModalConfigure( TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled); /* * Q3Renderer_GetPrivateData * Allows an application to collect private renderer configuration data * which it will then save. For example in a preference file or in a * style template. An application should tag this data with the * Renderer's object name. * * if dataBuffer is NULL actualDataSize returns the required size in * bytes of a data buffer large enough to store private data. * * bufferSize in the actual size of the memory block pointed to by * dataBuffer * * actualDataSize - on return the actual number of bytes written to the * buffer or if dataBuffer is NULL the required size of dataBuffer * */ QD3D_EXPORT TQ3Status Q3Renderer_GetPrivateData( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize); QD3D_EXPORT TQ3Status Q3Renderer_SetPrivateData( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize); /****************************************************************************** ** ** ** Interactive Renderer Specific Functions ** ** ** *****************************************************************************/ /* * CSG IDs attribute */ #define kQ3AttributeTypeConstructiveSolidGeometryID \ Q3_OBJECT_TYPE('c','s','g','i') #if defined(QD3D_OBSOLETE) && QD3D_OBSOLETE #define kQ3AttributeType_ConstructiveSolidGeometryID \ kQ3AttributeTypeConstructiveSolidGeometryID #endif /* QD3D_OBSOLETE */ /* * Object IDs, to be applied as attributes on geometries */ #define kQ3SolidGeometryObjA 0 #define kQ3SolidGeometryObjB 1 #define kQ3SolidGeometryObjC 2 #define kQ3SolidGeometryObjD 3 #define kQ3SolidGeometryObjE 4 /* * Possible CSG equations */ typedef enum TQ3CSGEquation { kQ3CSGEquationAandB = (int)0x88888888, kQ3CSGEquationAandnotB = 0x22222222, kQ3CSGEquationAanBonCad = 0x2F222F22, kQ3CSGEquationnotAandB = 0x44444444, kQ3CSGEquationnAaBorCanB = 0x74747474 } TQ3CSGEquation; typedef enum TQ3HiddenSurfaceRemovalMode { kQ3HiddenSurfaceRemovalMode_None, kQ3HiddenSurfaceRemovalMode_Shallow, kQ3HiddenSurfaceRemovalMode_Deep } TQ3HiddenSurfaceRemovalMode; QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetCSGEquation( TQ3RendererObject renderer, TQ3CSGEquation equation); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetCSGEquation( TQ3RendererObject renderer, TQ3CSGEquation *equation); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetPreferences( TQ3RendererObject renderer, long vendorID, long engineID); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetPreferences( TQ3RendererObject renderer, long *vendorID, long *engineID); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetDoubleBufferBypass( TQ3RendererObject renderer, TQ3Boolean bypass); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetDoubleBufferBypass( TQ3RendererObject renderer, TQ3Boolean *bypass); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetHiddenSurfaceRemovalMode( TQ3RendererObject renderer, TQ3HiddenSurfaceRemovalMode hiddenSurfaceRemovalMode); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetHiddenSurfaceRemovalMode( TQ3RendererObject renderer, TQ3HiddenSurfaceRemovalMode *hiddenSurfaceRemovalMode); /****************************************************************************** ** ** ** Plug-in Renderer API ** ** ** *****************************************************************************/ /* * These bits should be set in the flag to indicate class supported */ #define kQ3XRendererClassSupportNone (0) /* nothing */ #define kQ3XRendererClassSupportFlagDoubleBuffer (1U << 0) /* Handle Double buffering */ #define kQ3XRendererClassSupportFlagClearBuffer (1U << 1) /* Handle DrawContext clearing */ typedef unsigned long TQ3XRendererClassSupportFlags; /* * Registration */ QD3D_EXPORT TQ3XObjectClass Q3XRendererClass_Register( TQ3ObjectType objectType, char *rendererName, TQ3XMetaHandler metaHandler, unsigned long sizeofClassPrivate, unsigned long sizeofDataPrivate); /****************************************************************************** ** ** ** Renderer View Tools ** ** ** ** You may only call these methods from a plug-in ** ** ** *****************************************************************************/ /* * Call by a renderer to call the user "idle" method, with progress * information. * * Pass in (view, 0, n) on first call * Pass in (view, 1..n-1, n) during rendering * Pass in (view, n, n) upon completion * * Note: The user must have supplied an idleProgress method with * Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is * called with no progress data. e.g. the Q3View_SetIdleMethod method * is called instead. (current and final are ignored, essentially.) * * Returns kQ3Failure if rendering is cancelled. */ QD3D_EXPORT TQ3Status Q3XView_IdleProgress( TQ3ViewObject view, unsigned long current, unsigned long completed); /* * Called by an asynchronous renderer when it completes a frame. */ QD3D_EXPORT TQ3Status Q3XView_EndFrame( TQ3ViewObject view); /****************************************************************************** ** ** ** Renderer AttributeSet Tools ** ** ** ** You may only call these methods from a plug-in ** ** ** *****************************************************************************/ /* * Faster access to geometry attribute sets. * * Returns pointer to INTERNAL data structure for elements and attributes * in an attributeSet, or NULL if no attribute exists. * * For attributes of type kQ3AttributeType..., the internal data structure * is identical to the data structure used in Q3AttributeSet_Add. */ QD3D_EXPORT void *Q3XAttributeSet_GetPointer( TQ3AttributeSet attributeSet, TQ3AttributeType attributeType); #define kQ3XAttributeMaskNone \ 0L #define kQ3XAttributeMaskSurfaceUV \ (1 << (kQ3AttributeTypeSurfaceUV - 1)) #define kQ3XAttributeMaskShadingUV \ (1 << (kQ3AttributeTypeShadingUV - 1)) #define kQ3XAttributeMaskNormal \ (1 << (kQ3AttributeTypeNormal - 1)) #define kQ3XAttributeMaskAmbientCoefficient \ (1 << (kQ3AttributeTypeAmbientCoefficient - 1)) #define kQ3XAttributeMaskDiffuseColor \ (1 << (kQ3AttributeTypeDiffuseColor - 1)) #define kQ3XAttributeMaskSpecularColor \ (1 << (kQ3AttributeTypeSpecularColor - 1)) #define kQ3XAttributeMaskSpecularControl \ (1 << (kQ3AttributeTypeSpecularControl - 1)) #define kQ3XAttributeMaskTransparencyColor \ (1 << (kQ3AttributeTypeTransparencyColor - 1)) #define kQ3XAttributeMaskSurfaceTangent \ (1 << (kQ3AttributeTypeSurfaceTangent - 1)) #define kQ3XAttributeMaskHighlightState \ (1 << (kQ3AttributeTypeHighlightState - 1)) #define kQ3XAttributeMaskSurfaceShader \ (1 << (kQ3AttributeTypeSurfaceShader - 1)) #define kQ3XAttributeMaskCustomAttribute 0x80 #define kQ3XAttributeMaskAll \ ( \ kQ3XAttributeMaskSurfaceUV | \ kQ3XAttributeMaskShadingUV | \ kQ3XAttributeMaskNormal | \ kQ3XAttributeMaskAmbientCoefficient | \ kQ3XAttributeMaskDiffuseColor | \ kQ3XAttributeMaskSpecularColor | \ kQ3XAttributeMaskSpecularControl | \ kQ3XAttributeMaskTransparencyColor | \ kQ3XAttributeMaskSurfaceTangent | \ kQ3XAttributeMaskHighlightState | \ kQ3XAttributeMaskSurfaceShader | \ kQ3XAttributeMaskCustomAttribute \ ) #define kQ3XAttributeMaskInherited \ ( \ kQ3XAttributeMaskSurfaceUV | \ kQ3XAttributeMaskShadingUV | \ kQ3XAttributeMaskNormal | \ kQ3XAttributeMaskAmbientCoefficient | \ kQ3XAttributeMaskDiffuseColor | \ kQ3XAttributeMaskSpecularColor | \ kQ3XAttributeMaskSpecularControl | \ kQ3XAttributeMaskTransparencyColor | \ kQ3XAttributeMaskSurfaceTangent | \ kQ3XAttributeMaskHighlightState \ ) #define kQ3XAttributeMaskInterpolated \ ( \ kQ3XAttributeMaskSurfaceUV | \ kQ3XAttributeMaskShadingUV | \ kQ3XAttributeMaskNormal | \ kQ3XAttributeMaskAmbientCoefficient | \ kQ3XAttributeMaskDiffuseColor | \ kQ3XAttributeMaskSpecularColor | \ kQ3XAttributeMaskSpecularControl | \ kQ3XAttributeMaskTransparencyColor | \ kQ3XAttributeMaskSurfaceTangent | \ ) typedef unsigned long TQ3XAttributeMask; QD3D_EXPORT TQ3XAttributeMask Q3XAttributeSet_GetMask( TQ3AttributeSet attributeSet); /****************************************************************************** ** ** ** Renderer Draw Context Tools ** ** ** *****************************************************************************/ typedef struct TQ3XDrawRegionPrivate *TQ3XDrawRegion; QD3D_EXPORT TQ3Status Q3XDrawContext_GetDrawRegion( TQ3DrawContextObject drawContext, TQ3XDrawRegion *drawRegion); typedef enum TQ3XDrawContextValidationMasks { kQ3XDrawContextValidationClearFlags = 0x00000000L, kQ3XDrawContextValidationDoubleBuffer = 1 << 0, kQ3XDrawContextValidationShader = 1 << 1, kQ3XDrawContextValidationClearFunction = 1 << 2, kQ3XDrawContextValidationActiveBuffer = 1 << 3, kQ3XDrawContextValidationInternalOffScreen = 1 << 4, kQ3XDrawContextValidationPane = 1 << 5, kQ3XDrawContextValidationMask = 1 << 6, kQ3XDrawContextValidationDevice = 1 << 7, kQ3XDrawContextValidationWindow = 1 << 8, kQ3XDrawContextValidationWindowSize = 1 << 9, kQ3XDrawContextValidationWindowClip = 1 << 10, kQ3XDrawContextValidationWindowPosition = 1 << 11, kQ3XDrawContextValidationPlatformAttributes = 1 << 12, kQ3XDrawContextValidationForegroundShader = 1 << 13, kQ3XDrawContextValidationBackgroundShader = 1 << 14, kQ3XDrawContextValidationAll = ~0 } TQ3XDrawContextValidationMasks; typedef unsigned long TQ3XDrawContextValidation; QD3D_EXPORT TQ3Status Q3XDrawContext_ClearValidationFlags( TQ3DrawContextObject drawContext); QD3D_EXPORT TQ3Status Q3XDrawContext_GetValidationFlags( TQ3DrawContextObject drawContext, TQ3XDrawContextValidation *validationFlags); /****************************************************************************** ** ** ** Renderer Draw Region Tools ** ** ** *****************************************************************************/ typedef enum TQ3XClipMaskState { kQ3XClipMaskFullyExposed, kQ3XClipMaskPartiallyExposed, kQ3XClipMaskNotExposed } TQ3XClipMaskState; typedef struct TQ3XDrawRegionClipMask { unsigned char *image; unsigned long width; unsigned long height; unsigned long rowBytes; TQ3Endian bitOrder; } TQ3XDrawRegionClipMask; typedef struct TQ3XDrawRegionDescriptor { unsigned long width; unsigned long height; unsigned long rowBytes; unsigned long pixelSize; TQ3PixelType pixelType; TQ3Endian bitOrder; TQ3Endian byteOrder; } TQ3XDrawRegionDescriptor; typedef void (*TQ3XDrawRegionRendererPrivateDeleteMethod)( void *rendererPrivate); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetDeviceScaleX( TQ3XDrawRegion drawRegion, float *deviceScaleX); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetDeviceScaleY( TQ3XDrawRegion drawRegion, float *deviceScaleY); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetDeviceOffsetX( TQ3XDrawRegion drawRegion, float *deviceOffsetX); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetDeviceOffsetY( TQ3XDrawRegion drawRegion, float *deviceOffsetX); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetWindowScaleX( TQ3XDrawRegion drawRegion, float *windowScaleX); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetWindowScaleY( TQ3XDrawRegion drawRegion, float *windowScaleY); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetWindowOffsetX( TQ3XDrawRegion drawRegion, float *windowOffsetX); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetWindowOffsetY( TQ3XDrawRegion drawRegion, float *windowOffsetY); QD3D_EXPORT TQ3Status Q3XDrawRegion_IsActive( TQ3XDrawRegion drawRegion, TQ3Boolean *isActive); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetNextRegion( TQ3XDrawRegion drawRegion, TQ3XDrawRegion *nextDrawRegion); QD3D_EXPORT TQ3Status Q3XDrawRegion_Start( TQ3XDrawRegion drawRegion, TQ3Boolean clear); QD3D_EXPORT TQ3Status Q3XDrawRegion_End( TQ3XDrawRegion drawRegion); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetDeviceTransform( TQ3XDrawRegion drawRegion, TQ3Matrix4x4 **deviceTransform); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetClipFlags( TQ3XDrawRegion drawRegion, TQ3XClipMaskState *clipMaskState); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetClipMask( TQ3XDrawRegion drawRegion, TQ3XDrawRegionClipMask **clipMask); #if defined(WINDOW_SYSTEM_MACINTOSH) && WINDOW_SYSTEM_MACINTOSH QD3D_EXPORT TQ3Status Q3XDrawRegion_GetClipRegion( TQ3XDrawRegion drawRegion, RgnHandle *rgnHandle); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetGDHandle( TQ3XDrawRegion drawRegion, GDHandle *gdHandle); #endif /* WINDOW_SYSTEM_MACINTOSH */ QD3D_EXPORT TQ3Status Q3XDrawRegion_GetRendererPrivate( TQ3XDrawRegion drawRegion, void **rendererPrivate); QD3D_EXPORT TQ3Status Q3XDrawRegion_SetRendererPrivate( TQ3XDrawRegion drawRegion, const void *rendererPrivate, TQ3XDrawRegionRendererPrivateDeleteMethod deleteMethod); QD3D_EXPORT TQ3Status Q3XDrawRegion_SetUseDefaultRendererFlag( TQ3XDrawRegion drawRegion, TQ3Boolean flag); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetUseDefaultRendererFlag( TQ3XDrawRegion drawRegion, TQ3Boolean *useDefaultRenderingFlag); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetNativeDescriptor( TQ3XDrawRegion drawRegion, const TQ3XDrawRegionDescriptor **descriptor); QD3D_EXPORT TQ3Status Q3XDrawRegion_UseDescriptor( TQ3XDrawRegion drawRegion, const TQ3XDrawRegionDescriptor *descriptor); QD3D_EXPORT TQ3Status Q3XDrawRegion_GetImage( TQ3XDrawRegion drawRegion, void **image); QD3D_EXPORT TQ3Status Q3XDrawRegion_LookupColor( TQ3XDrawRegion drawRegion, float red, float green, float blue, float alpha, unsigned long *pixelValue); QD3D_EXPORT TQ3Status Q3XDrawRegion_PutPixel( TQ3XDrawRegion drawRegion, unsigned long x, unsigned long y, float red, float green, float blue, float alpha); QD3D_EXPORT TQ3Status Q3XDrawRegion_PutRaster( TQ3XDrawRegion drawRegion, unsigned long x, unsigned long y, unsigned long width, unsigned long height, const TQ3ColorARGB *raster); /****************************************************************************** ** ** ** Renderer Class Methods ** ** ** *****************************************************************************/ /* * Methods from Object * kQ3XMethodTypeObjectClassRegister * kQ3XMethodTypeObjectClassUnregister * kQ3XMethodTypeObjectNew * kQ3XMethodTypeObjectDelete * kQ3XMethodTypeObjectRead * kQ3XMethodTypeObjectTraverse * kQ3XMethodTypeObjectWrite * * Methods from Shared * kQ3MethodTypeSharedEdited * * Renderer Methods * * The renderer methods should be implemented according to the type * of renderer being written. * * For the purposes of documentation, there are two basic types of * renderers: * * Interactive * Interactive Renderer * WireFrame Renderer * * Deferred * a ray-tracer * painter's algorithm renderer (cached in a BSP triangle tree) * an artistic renderer (simulates a pencil drawing, etc.) * * The main difference is how each renderer handles incoming state and * geometry. * * An interactive renderer immediately transforms, culls, and shades * incoming geometry and performs rasterization. For example, in a * single-buffered WireFrame renderer, you will see a new triangle * immediately after Q3Triangle_Draw (if it's visible, of course). * * A deferred renderer caches the view state and each geometry, * converting into any internal queue of drawing commands. Rasterization * is not actually performed until all data has been submitted. * * For example, a ray-tracer may not rasterize anything until the * end of the rendering loop, or until an EndFrame call is made. */ /****************************************************************************** ** ** ** Renderer Support Flags ** ** ** *****************************************************************************/ /* * kQ3XMethodTypeRendererClassSupportFlag * TQ3XRendererClassSupportFlagMethod * * Return the TQ3XRendererClassSupportFlags for your renderer class. * * kQ3XRendererClassSupportFlagDoubleBuffer * - the drawContext will not allocate or manage a back image buffer * - you must update the front buffer * kQ3XRendererClassSupportFlagClearBuffer * - the drawContext will not be cleared before startFrame * - you must clear the image buffer with the desired drawcontext * method. * * If no method is supplied, the default is 0L. * * OPTIONAL */ #define kQ3XMethodTypeRendererClassSupportFlag \ Q3_METHOD_TYPE('r','d','s','f') typedef TQ3XRendererClassSupportFlags TQ3XRendererClassSupportFlagMethod; /* * kQ3XMethodTypeRendererGetEditFeatures * TQ3XRendererGetEditFeaturesMethod * * Return the TQ3RendererFeatureFlags of the editable features of your * renderer. * * If no method is supplied, or the kQ3MethodTypeRendererSetFeatures is * NULL, the default editableFlags is kQ3RendererFeatureNone. * * OPTIONAL */ #define kQ3XMethodTypeRendererGetEditFeatures \ Q3_METHOD_TYPE('r','d','f','e') typedef TQ3Status (*TQ3XRendererGetEditFeaturesMethod)( TQ3RendererObject renderer, void *rendererPrivate, TQ3RendererFeatureFlags *editableFlags); /* * kQ3MethodTypeRendererGetFeatures * TQ3XRendererGetFeaturesMethod * * Return the TQ3XRendererFeatureFlags of the current features set in * your renderer. * * If no method is supplied, the default flags is kQ3RendererFeatureNone. * * OPTIONAL */ #define kQ3XMethodTypeRendererGetFeatures \ Q3_METHOD_TYPE('r','d','f','g') typedef TQ3Status (*TQ3XRendererGetFeaturesMethod)( TQ3RendererObject renderer, void *rendererPrivate, TQ3RendererFeatureFlags *flags); /* * kQ3XMethodTypeRendererSetFeatures * TQ3XRendererSetFeaturesMethod * * Set the TQ3RendererFeatureFlags in the current features set of * your renderer. * * Operation is: * newRendererFlags = * (oldRendererFlags & ~editableFlags) | * (flags & editableFlags); * * If no method is supplied, the Q3Renderer_GetEditFeatures always returns * kQ3RendererFeatureNone. * * OPTIONAL */ #define kQ3XMethodTypeRendererSetFeatures \ Q3_METHOD_TYPE('r','d','f','s') typedef TQ3Status (*TQ3XRendererSetFeaturesMethod)( TQ3RendererObject renderer, void *rendererPrivate, TQ3RendererFeatureFlags flags); /****************************************************************************** ** ** ** Renderer User Interface Methods ** ** ** *****************************************************************************/ /* * TQ3XRendererModalConfigureMethod * * This method should pop up a modal dialog to edit the renderer settings * found in the renderer private. * * dialogAnchor - is platform specific data passed by the client to support * movable modal dialogs. * MacOS: this is a callback to the calling application's event handler. * The renderer calls this function with events not handled by the * settings dialog. This is necessary in order to support movable modal * dialogs. An application's event handler must return kQ3True if it * handles the event passed to the callback or kQ3False if not. * An application which doesn't want to support a movable modal configure * dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor. * A renderer should implement a non-movable style dialog in that case. * Win32: this is the HWND of the owning window (typically an application's * main window). (Win32 application modal dialogs are always movable.) * canceled - returns a boolean inditacating that the user canceled the * dialog. * * OPTIONAL */ #define kQ3XMethodTypeRendererModalConfigure \ Q3_METHOD_TYPE('r','d','m','c') typedef TQ3Status (*TQ3XRendererModalConfigureMethod)( TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled, void *rendererPrivate); /* * TQ3XRendererGetPrivateDataMethod * * Allows an application to collect private configuration data from the * renderer * which it will then save. For example in a preference file or in a * style template. An application should tag this data with the * Renderer's object name. * * if dataBuffer is NULL actualDataSize returns the required size in * bytes of a data bufferlarge enough to store private data. * * bufferSize in the actual size of the memory block pointed to by * dataBuffer * * actualDataSize - on return the actual number of bytes written to the * buffer or if dataBuffer is NULL the required size of dataBuffer * * OPTIONAL */ #define kQ3XMethodTypeRendererGetPrivateData \ Q3_METHOD_TYPE('r','d','g','p') typedef TQ3Status (*TQ3XRendererGetPrivateDataMethod)( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize, void *rendererPrivate); /* * TQ3XRendererSetPrivateDataMethod * * Allows an application to pass private configuration data which has previously * been obtained from a renderer via Q3Renderer_GetPrivateData. For example in a * preference file or in a style * template. An application should tag this data with the Renderer's object * name. * * if dataBuffer is NULL returns the required size in bytes of a data buffer * large enough to store private data. * * bufferSize in the actual size of the memory block pointed to by dataBuffer * * if dataBuffer is not NULL the return value is the actual number of bytes * written to the dataBuffer. * * OPTIONAL */ #define kQ3XMethodTypeRendererSetPrivateData \ Q3_METHOD_TYPE('r','d','s','p') typedef TQ3Status (*TQ3XRendererSetPrivateDataMethod)( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer Drawing State Methods ** ** ** *****************************************************************************/ /* * TQ3RendererStartFrame * * The StartFrame method is called first at Q3View_StartRendering * and should: * - initialize any renderer state to defaults * - extract any and all useful data from the drawContext * * If your renderer passed in kQ3RendererFlagClearBuffer at * registration, then it should also: * - clear the drawContext * * When clearing, your renderer may opt to: * - NOT clear anything (if you touch every pixel, for example) * - to clear with your own routine, or * - to use the draw context default clear method by calling * Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of * any available hardware in the system for clearing. * * This call also signals the start of all default submit commands from * the view. The renderer will receive updates for the default view * state via its Update methods before StartPass is called. * * REQUIRED */ #define kQ3XMethodTypeRendererStartFrame \ Q3_METHOD_TYPE('r','d','c','l') typedef TQ3Status (*TQ3XRendererStartFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /* * kQ3XMethodTypeRendererStartPass * TQ3XRendererStartPassMethod * * The StartPass method is called during Q3View_StartRendering but after * the StartFrame command. It should: * - collect camera and light information * * If your renderer supports deferred camera transformation, camera is the * main camera which will be submitted in the hierarchy somewhere. It * is never NULL. * * If your renderer does not support deferred camera transformation, camera * is the transformed camera. * * If your renderer supports deferred light transformation, lights will be * NULL, and will be submitted to your light draw methods instead. * * This call signals the end of the default update state, and the start of submit * commands from the user to the view. * * REQUIRED */ #define kQ3XMethodTypeRendererStartPass \ Q3_METHOD_TYPE('r','d','s','t') typedef TQ3Status (*TQ3XRendererStartPassMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, TQ3GroupObject lightGroup); /* * kQ3XMethodTypeRendererFlushFrame * TQ3XRendererFlushFrameMethod * * This call is only implemented by asynchronous renderers. * * The FlushFrame method is called between the StartPass and EndPass * methods and is called when the user wishes to flush any asynchronous * drawing tasks (which draw to the drawcontext), but does not want * to block. * * The result of this call is that an image should "eventually" appear * asynchronously. * * For asynchronous rendering, this call is non-blocking. * * An interactive renderer should ensure that all received * geometries are drawn in the image. * * An interactive renderer that talks to hardware should force * the hardware to generate an image. * * A deferred renderer should exhibit a similar behaviour, * though it is not required. A deferred renderer should spawn * a process that generates a partial image from the currently * accumulated drawing state. * * However, for renderers such as ray-tracers which generally are * quite compute-intensive, FlushFrame is not required and is a no-op. * * OPTIONAL */ #define kQ3XMethodTypeRendererFlushFrame \ Q3_METHOD_TYPE('r','d','f','l') typedef TQ3Status (*TQ3XRendererFlushFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /* * kQ3XMethodTypeRendererEndPass * TQ3XRendererEndPassMethod * * The EndPass method is called at Q3View_EndRendering and signals * the end of submit commands to the view. * * If an error occurs, the renderer should call Q3XError_Post and * return kQ3ViewStatusError. * * If a renderer requires another pass on the renderering data, * it should return kQ3ViewStatusRetraverse. * * If rendering was cancelled, this function will not be called * and the view will handle returning kQ3ViewStatusCancelled; * * Otherwise, your renderer should begin completing the process of * generating the image in the drawcontext. If you have buffered * any drawing data, flush it. RendererEnd should have a similar * effect as RendererFlushFrame. * * If the renderer is synchronous: * - complete rendering of the entire frame * if the renderer supports kQ3RendererClassSupportDoubleBuffer * - Update the front buffer * else * - DrawContext will update the front buffer after returning * * If the renderer is asynchronous * - spawn rendering thread for entire frame * if the renderer supports kQ3RendererClassSupportDoubleBuffer, * - you must eventually update the front buffer asynchronously * else * - you must eventually update the back buffer asynchronously * * REQUIRED */ #define kQ3XMethodTypeRendererEndPass \ Q3_METHOD_TYPE('r','d','e','d') typedef TQ3ViewStatus (*TQ3XRendererEndPassMethod)( TQ3ViewObject view, void *rendererPrivate); /* * kQ3XMethodTypeRendererEndFrame * TQ3XRendererEndFrame * * This call is only implemented by asynchronous renderers. * * The EndFrame method is called from Q3View_Sync, which is * called after Q3View_EndRendering and signals that the user * wishes to see the completed image and is willing to block. * * If your renderer supports kQ3RendererFlagDoubleBuffer * - update the front buffer completely * else * - update the back buffer completely * * This call is equivalent in functionality to RendererFlushFrame * but blocks until the image is completed. * * If no method is supplied, the default is a no-op. * * NOTE: Registering a method of this type indicates that your renderer will * be rendering after Q3View_EndRendering has been called. * * OPTIONAL */ #define kQ3XMethodTypeRendererEndFrame \ Q3_METHOD_TYPE('r','d','s','y') typedef TQ3Status (*TQ3XRendererEndFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /* * The RendererCancel method is called after Q3View_StartRendering * and signals the termination of all rendering operations. * * A renderer should clean up any cached data, and cancel all * rendering operations. * * If called before Q3View_EndRendering, the RendererEnd method * is NOT called. * * If called after Q3View_EndRendering, the renderer should kill * any threads and terminate any further rendering. * * REQUIRED */ #define kQ3XMethodTypeRendererCancel \ Q3_METHOD_TYPE('r','d','a','b') typedef void (*TQ3XRendererCancelMethod)( TQ3ViewObject view, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer DrawContext Methods ** ** ** *****************************************************************************/ /* * kQ3XMethodTypeRendererPush * TQ3XRendererPushMethod * * kQ3XMethodTypeRendererPop * TQ3XRendererPopMethod * * These methods are called whenever the graphics state in the view * is pushed or popped. The user may isolate state by calling: * * Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view); * Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view); * Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view); * Q3Box_Submit(&unitBox, view); * Q3TranslateTransform_Submit(&unitVector, view); * Q3Push_Submit(view); * Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view); * Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view); * Q3Box_Submit(&unitBox, view); * Q3Pop_Submit(view); * Q3TranslateTransform_Submit(&unitVector, view); * Q3Box_Submit(&unitBox, view); * * or by submitting a display group which pushes and pops. * * If you support RendererPush and RendererPop in your renderer: * - you must maintain your drawing state as a stack, as well. * - you will not be updated with the popped state after * RendererPop is called. * * If you do not support Push and Pop in your renderer: * - you may maintain a single copy of the drawing state. * - you will be updated with changed fields after the view stack is * popped. * * A renderer that supports Push and Pop gets called in the following * sequence (from example above): * * RendererUpdateAttributeDiffuseColor(&red,...) * RendererUpdateAttributeTransparencyColor(&blue,...) * RendererUpdateAttributeSpecularColor(&white,...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * RendererPush(...) * RendererUpdateAttributeDiffuseColor(&blue,...) * RendererUpdateAttributeTransparencyColor(&green,...) * RendererSubmitGeometryBox(...) * RendererPop(...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * * A renderer that does not supports Push and Pop gets called in the * following sequence: * * RendererUpdateAttributeDiffuseColor(&red,...) * RendererUpdateAttributeTransparencyColor(&blue,...) * RendererUpdateAttributeSpecularColor(&white,...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * RendererUpdateAttributeDiffuseColor(&blue,...) * RendererUpdateAttributeTransparencyColor(&green,...) * RendererSubmitGeometryBox(...) * RendererUpdateAttributeDiffuseColor(&red,...) * RendererUpdateAttributeTransparencyColor(&blue,...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * */ #define kQ3XMethodTypeRendererPush \ Q3_METHOD_TYPE('r','d','p','s') typedef TQ3Status (*TQ3XRendererPushMethod)( TQ3ViewObject view, void *rendererPrivate); #define kQ3XMethodTypeRendererPop \ Q3_METHOD_TYPE('r','d','p','o') typedef TQ3Status (*TQ3XRendererPopMethod)( TQ3ViewObject view, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer Cull Methods ** ** ** *****************************************************************************/ /* * kQ3XMethodTypeRendererIsBoundingBoxVisible * TQ3XRendererIsBoundingBoxVisibleMethod * * This method is called to cull complex groups and geometries * given their bounding box in local space. * * It should transform the local-space bounding box coordinates to * frustum space and return a TQ3Boolean return value indicating * whether the box appears within the viewing frustum. * * If no method is supplied, the default behvaiour is to return * kQ3True. * * TODO: Default to cull to { (-1,1), (-1,1), (0,1) } frustum? */ #define kQ3XMethodTypeRendererIsBoundingBoxVisible \ Q3_METHOD_TYPE('r','d','b','x') typedef TQ3Boolean (*TQ3XRendererIsBoundingBoxVisibleMethod)( TQ3ViewObject view, void *rendererPrivate, const TQ3BoundingBox *bBox); /****************************************************************************** ** ** ** Renderer Object Support Methods ** ** ** *****************************************************************************/ /* * Drawing methods (Geometry, Camera, Lights) * */ /* * Geometry MetaHandler * * This metaHandler is required to support * * kQ3GeometryTypeTriangle * kQ3GeometryTypeLine * kQ3GeometryTypePoint * kQ3GeometryTypeMarker * kQ3GeometryTypePixmapMarker * * REQUIRED */ #define kQ3XMethodTypeRendererSubmitGeometryMetaHandler \ Q3_METHOD_TYPE('r','d','g','m') typedef TQ3XFunctionPointer (*TQ3XRendererSubmitGeometryMetaHandlerMethod)( TQ3ObjectType geometryType); /* * The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType * of kQ3GeometryTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3XRendererSubmitGeometryMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3GeometryObject geometry, const void *publicData); /* * Camera MetaHandler * * This metaHandler, if supplied, indicates that your renderer * handles deferred transformation of the main camera within a scene. * * If not supplied, or an unsupported camera is used, the view will do * the transformation for the renderer and pass in a camera in the * StartPass method. * * OPTIONAL */ #define kQ3XMethodTypeRendererSubmitCameraMetaHandler \ Q3_METHOD_TYPE('r','d','c','m') typedef TQ3XFunctionPointer (*TQ3XRendererSubmitCameraMetaHandlerMethod)( TQ3ObjectType cameraType); /* * The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType * of kQ3CameraTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3XRendererSubmitCameraMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, const void *publicData); /* * Light MetaHandler * * This metaHandler, if supplied, indicates that your renderer * handles deferred transformation of lights within a scene. * * If an unsupported light is encountered, it is ignored. * * OPTIONAL */ #define kQ3XMethodTypeRendererSubmitLightMetaHandler \ Q3_METHOD_TYPE('r','d','l','g') typedef TQ3XFunctionPointer (*TQ3XRendererSubmitLightMetaHandlerMethod)( TQ3ObjectType lightType); /* * The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType * of kQ3LightTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3XRendererSubmitLightMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3LightObject light, const void *publicData); /* * * Update methods * * They are called whenever the state has changed. If the renderer supports * the RendererPush and RendererPop methods, it must maintain its own state * stack. Updates are not called for changed data when the view stack is * popped. * * See the comments for the RendererPush and RendererPop methods above * for an example of how data is updated. * */ /* * Style */ #define kQ3XMethodTypeRendererUpdateStyleMetaHandler \ Q3_METHOD_TYPE('r','d','y','u') typedef TQ3XFunctionPointer (*TQ3XRendererUpdateStyleMetaHandlerMethod)( TQ3ObjectType styleType); /* * The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType * of kQ3StyleTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3XRendererUpdateStyleMethod)( TQ3ViewObject view, void *rendererPrivate, const void *publicData); /* * Attributes */ #define kQ3XMethodTypeRendererUpdateAttributeMetaHandler \ Q3_METHOD_TYPE('r','d','a','u') typedef TQ3XFunctionPointer (*TQ3XRendererUpdateAttributeMetaHandlerMethod)( TQ3AttributeType attributeType); /* * The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType * of kQ3AttributeTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3XRendererUpdateAttributeMethod)( TQ3ViewObject view, void *rendererPrivate, const void *publicData); /* * Shaders */ #define kQ3XMethodTypeRendererUpdateShaderMetaHandler \ Q3_METHOD_TYPE('r','d','s','u') typedef TQ3XFunctionPointer (*TQ3XRendererUpdateShaderMetaHandlerMethod)( TQ3ObjectType shaderType); /* * The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType * of kQ3ShaderTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3XRendererUpdateShaderMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3Object shaderObject); /* * Matrices */ #define kQ3XMethodTypeRendererUpdateMatrixMetaHandler \ Q3_METHOD_TYPE('r','d','x','u') typedef TQ3XMetaHandler TQ3XRendererUpdateMatrixMetaHandlerMethod; /* * The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods * of the form kQ3MethodTypeRendererUpdateMatrixFoo: */ #define kQ3XMethodTypeRendererUpdateMatrixLocalToWorld \ Q3_METHOD_TYPE('u','l','w','x') #define kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse \ Q3_METHOD_TYPE('u','l','w','i') #define kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose \ Q3_METHOD_TYPE('u','l','w','t') #define kQ3XMethodTypeRendererUpdateMatrixLocalToCamera \ Q3_METHOD_TYPE('u','l','c','x') #define kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum \ Q3_METHOD_TYPE('u','l','f','x') #define kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum \ Q3_METHOD_TYPE('u','w','f','x') /* * and returns methods of type: */ typedef TQ3Status (*TQ3XRendererUpdateMatrixMethod)( TQ3ViewObject view, void *rendererPrivate, const TQ3Matrix4x4 *matrix); #ifdef __cplusplus } #endif /* __cplusplus */ #if defined(__MWERKS__) #pragma enumsalwaysint reset #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__) #pragma options enum=reset #endif #endif /* QD3DRenderer_h */